Skip to content

docs(governed): record the allowOrgOverride → allowEnvironmentOverlay rename in AGENTS.md rule 7, the objectstack-ai skill and the ADR-0005 / ADR-0010 headers (#22340 S3) - #23011

Merged
os-zhuang merged 2 commits into
mainfrom
claude/issue-22340-s3-governed-text-rename
Oct 12, 2026
Merged

docs(governed): record the allowOrgOverride → allowEnvironmentOverlay rename in AGENTS.md rule 7, the objectstack-ai skill and the ADR-0005 / ADR-0010 headers (#22340 S3)#23011
os-zhuang merged 2 commits into
mainfrom
claude/issue-22340-s3-governed-text-rename

Conversation

@objectstack-fleet

@objectstack-fleet objectstack-fleet Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Part of #22340 (S3)
Clause-②: no

S3 of #22340 — the governed-text half of the allowOrgOverride → allowEnvironmentOverlay rename. S2 (the key, its tombstone, the retired-keys entry, the D3 semantic entry and the /meta/types wire field) landed in PR #22874 (e23eccb164); this PR records that landed decision in governed text and changes no semantics. Ruling followed: 6073921182 (Q1 A · Q2 A, maintainer 「同意」); shape: triage 6121122315 — the two normative lines edited in place, a header amendment note on each ADR, history lines untouched, no residue. The card stays open for cloud's two test helpers. Five files, 22 changed lines (+18 / −4): four governed paths and one changeset — Tier H, draft only; an authorized APPROVED review lands it. Session session_01CinRQcE6T8SvMbhH8D3NhS, dispatched under claim 6121201470.

Per-file before / after

AGENTS.md rule 7 (lines 191–192) — in place, same line count

Before:

   `packages/spec/src/{domain}/`. Org overlay opt-in lives only in `allowOrgOverride` on
   `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005.

After:

   `packages/spec/src/{domain}/`. Environment-overlay opt-in lives only in `allowEnvironmentOverlay` on
   `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5.

Line ratchet (check:pm-skill-ratchet): AGENTS.md is 1109 lines (ceiling 1116; headroom 7) before and after; AGENTS.md: widest table row is 768 bytes (pin 768; headroom 0) before and after (rule 7 is a list item, not a table row). Net lines: 0. No issue or PR number added (check:pm-skill-id-lint: 34 files clean).

skills/objectstack-ai/SKILL.md line 347 — in place

Before: `allowOrgOverride:false`; ADR-0063 §2) and `os g agent` is retired: a

After: `allowEnvironmentOverlay:false`; ADR-0063 §2) and `os g agent` is retired: a

Token ratchet (check:skills-token-ratchet): skills/objectstack-ai/SKILL.md is 5540 tokens (ceiling 6806; headroom 1266) before → 5541 tokens (ceiling 6806; headroom 1265) after; no ceiling moved, no deletion needed. Lines: 421 → 421 (the file), 4409 → 4409 (all ten skills/*/SKILL.md summed); authored bundle total 144143 → 144144 tokens against a 154938 ceiling sum. Net lines for skills/**: 0. The new key is live in the implementation index (check:skill-identifier-liveness green). No issue or PR number in skills/**.

docs/adr/0005-metadata-customization-overlay.md — a note at the top, an Amended by entry

Added under the existing 「v5.0 update (2026)」 blockquote, in the same voice:

Protocol 18 update (2026-10-12, ADR-0131 C5, #22340): The per-type overlay opt-in on MetadataTypeRegistryEntry is spelled allowEnvironmentOverlay from protocol 18 (packages/spec/src/kernel/metadata-plugin.zod.ts#allowEnvironmentOverlay). ADR-0131 D6 retired the per-organization overlay axis, so the key now names the one scope it governs — whether an environment may overlay an item of this type that a managed package ships. The old key allowOrgOverride stays on the registry entry schema only as a tombstone that refuses at parse with the new name in its prescription: no second key, no alias, no conversion. The lines below that name allowOrgOverride describe the field as it was spelled when they were written and are preserved verbatim.

Appended to the **Amended by**: status line: , [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the per-type opt-in is spelled allowEnvironmentOverlay from protocol 18 — the note at the top of this record).

The body lines that name allowOrgOverride are untouched — 12 matching lines at BASE (:47, :68, :515, :518, :521, :537, :596, :704, :707, :718, :719, :728; the dispatch counted 13), each now two lines lower.

docs/adr/0010-metadata-protection-model.md — the same note, a new Amended by: header line

The note is the ADR-0005 text verbatim (one decision, recorded twice). The header block gains, after **Builds on:** and in the block's own **Key:** value style: **Amended by:** [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the type-level opt-in is spelled allowEnvironmentOverlay from protocol 18 — the note at the top of this record). Its nine body lines naming the old key (:19, :31, :94, :119, :122, :190, :297, :525, :605 at BASE) are untouched, each now three lines lower.

.changeset/22340-s3-governed-text-rename.md

'@objectstack/skills': patch — skills/** ships as @objectstack/skills (packages/skills/package.json; in the fixed group of .changeset/config.json; .changeset/pre.json is mode pre, tag next; precedent PR #22846 for #22825). No skip-changeset. AGENTS.md and docs/adr/** publish nothing.

Premises checked against origin/main 74c4b3435 (BASE)

  • git grep -n allowOrgOverride over the four files answers AGENTS.md:191, skills/objectstack-ai/SKILL.md:347, ADR-0005 × 12 lines, ADR-0010 × 9 lines — the sites the dispatch named (ADR-0005: 12 lines, not 13). After this PR: 0, 0, 13 (12 history lines + the note), 10 (9 + the note).
  • allowEnvironmentOverlay is declared in packages/spec/src/kernel/metadata-plugin.zod.ts (the z.object key, the allowOrgOverride tombstone beside it, DEFAULT_METADATA_TYPE_REGISTRY reading it); the notes anchor it as a symbol anchor, which check:adr-symbol-anchors accepts as a declaration site (2319 anchors across 142 records, 0 unresolved).
  • No open PR and no in-flight claim touches the four files; origin/main moved two commits between BASE and the merge below (147a0d1ac, 6a7eca686) and touched none of them.

Gates — run on the final commit 7362ce1 (5963d2cf6 merged with origin/main 6a7eca686)

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 53 commands for the 5 paths (41 at claim time on the four files; the changeset path adds the changeset families). Each was run with stdout and stderr redirected into its own log file and its exit code captured before any pipe, and --ran reconciled the record: 53 derived, 51 run at exit 0, 2 NOT MEASURED, 0 unrun (✓ dispatch-gates --ran: 53 derived famil(ies) accounted for — 51 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)).

Verdict lines from the 7362ce1 run:

  • ✓ check-skill-line-ratchet: AGENTS.md is 1109 lines (ceiling 1116; headroom 7). · ✓ check-skill-line-ratchet: AGENTS.md: widest table row is 768 bytes (pin 768; headroom 0).
  • ✓ check-skills-token-ratchet: skills/objectstack-ai/SKILL.md is 5541 tokens (ceiling 6806; headroom 1265). · ✓ check-skills-token-ratchet: 54 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.
  • ✓ check-skill-id-lint: 34 file(s) clean (pattern /#[0-9]{3,}/g).
  • check-skill-identifier-liveness OK — Leg 1: 457 citation(s) over 53 published file(s) checked against 126987 implementation word tokens (0 ledgered exemption(s)); Leg 2: 8 registered exhaustive section(s), 0 ledgered gap(s).
  • ✅ check-adr-symbol-anchors: 2319 anchors across 142 records resolve — 439 symbol (412 declaration, 27 literal), 1853 file-level, 27 cross-repo, 6 exempt, 18 continuation.
  • ✅ check-adr-links: 730 relative link destination(s) under docs/adr/ resolve
  • check-adr-anchors: OK (68 anchored file(s), every governing ADR still referenced; 136 decision number(s), each naming one decision or an allowlisted pair; 44050 citation(s) across 5831 file(s) resolve; 1624 decision-letter citation(s) on the anchored surface name a decision the record makes).
  • ✓ check-governed-prose: 2 instruction surface(s) name all 6 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md · docs/NORTH-STAR.md) and claim no others.
  • check-nul-bytes: OK (scanned 11012 text file(s) -- 11012 tracked, 0 untracked-not-ignored; skipped 9 binary; no raw ASCII control bytes).
  • ✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added). · ✓ This diff introduces no major bump.
  • ✅ Skill docs in sync (check:skill-docs, frontmatter unchanged) · ✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 473 files / 1388 TS blocks judged clean by @objectstack/formula. — measured after building @objectstack/formula and @objectstack/lint (with their closure: spec, types) under the shared verify lock (os-verify-lock: VERDICT command-exit 0 · held the lock 115s).
  • check-dts-closure: 4 built package(s) swept - 46/46 declared declaration file(s) present across 4 package(s) and check-sourcemap-no-sources-content: 4 built package(s) swept - 58 map(s), none embed source text — sweeps over the four packages that build left, not closure readings.

NOT MEASURED (declared, not green): pnpm check:dual-build-cjs-loads and pnpm check:lean-entry-closure exited 3 (PREREQUISITE NOT MET): the first loads the built exports of every workspace package (107 without a dist/), the second @objectstack/objectql's built entry points. This diff changes no file any package build reads — no packages/** source, manifest or tsconfig; @objectstack/skills's build is a byte copy of skills/** that emits no entry point, declaration or map — so the repo-wide build those two need is CI's run (Build Core, Lint & Repo Gates), not a local one. pnpm lint (repo-wide eslint) is likewise CI's: the diff has no lintable file. No package test / typecheck is owed (no package source changed); the packages/cli tiers do not apply.

Sibling #22998 (AGENTS.md: the merge-queue required-set paragraph and the gates section)

Not landed at my last merge of origin/main (6a7eca686, 2026-10-12T09:26Z): git log 74c4b3435..origin/main --grep=22998 is empty, and git diff 74c4b3435 origin/main -- AGENTS.md is empty. Region-disjoint from rule 7; if a later merge conflicts on AGENTS.md, both intents are kept.

Acceptance notes (observations; nothing filed)

  • scripts/adr-anchors/packages__spec__src__kernel__metadata-plugin.zod.ts.json cites docs/adr/0005-metadata-customization-overlay.md:53-64 (the whitelist table) in its invariant prose; the two-line note at the top of ADR-0005 moves that table to lines 55–66. No gate reads that range (check:adr-anchors verifies ADR ids and decision letters; check:adr-symbol-anchors sweeps docs/adr/**, not scripts/adr-anchors/**), and the file is outside this PR's governed-only surface. Carrier: the next PR that edits that anchor file. Not filed.
  • ADR-0063 line 135 (its §2 checklist, which the skill line cites) still spells the key allowOrgOverride:false — a history line of the class the triage left as written; the skill cites the decision, not the spelling. Not edited, not filed.

维护者速读(草稿)

改了什么:把「某类元数据能不能被环境覆盖」这个按类型的开关,在四份给 AI 和人读的治理文本里改成代码里现在的名字 allowEnvironmentOverlay(旧名 allowOrgOverride):AGENTS.md 第 7 条规则、对外发布的 objectstack-ai 技能里的一行,ADR-0005 与 ADR-0010 各在顶部加一段「协议 18 起改名」的说明并登记被 ADR-0131 修订;两份 ADR 正文里描述当年字段的历史叙述原样保留。另附一条 @objectstack/skills 的 patch changeset,因为那一行是随技能包发布的。

为什么改:改名本身(S2,PR #22874)已经合入,代码、类型和 /meta/types 返回都只认新名,旧名写出来会在解析时被拒绝并提示改名。但 AGENTS.md 和发布的技能还在教旧名 —— AI 照文档写出来的键会被运行时拒收,正是「文档与契约不一致」这类事故的源头。ADR 是决策档案,按 ADR-0005 自己已有的惯例(顶部的「v5.0 update」注)只加注、不改写历史。

风险与代价(含回滚):零运行时风险 —— 不改任何代码、schema 或行为,只改文字。本地门禁 53 项中 51 项通过,2 项需要整仓构建、留给 CI 测量。代价是 @objectstack/skills 下个版本多一条 patch 条目。回滚:revert 本 PR 即可,无数据、无迁移。

席位意见:

你要做的:这是 Tier H 治理面(AGENTS.md、skills/、docs/adr/),需要你或 GOVERNED_APPROVERS 中的授权账号在本 PR 上给一个 APPROVED review,之后由席位合入。确认两点即可:① 新名字 allowEnvironmentOverlay 与 S2 落地的一致;② ADR 顶部加注的写法(照 ADR-0005 的「v5.0 update」样式)你认可。

Generated by Claude Code

claude added 2 commits October 12, 2026 09:19
@claude
docs(governed): record the allowOrgOverride → allowEnvironmentOverlay…
5963d2c 
… rename in AGENTS.md rule 7, the objectstack-ai skill and the ADR-0005 / ADR-0010 headers (#22340 S3)

The key was renamed in protocol 18 (S2, the spec and metadata-protocol half); this is the governed-text half. AGENTS.md rule 7 and skills/objectstack-ai/SKILL.md name the new key in place, same line count. ADR-0005 and ADR-0010 each gain a blockquote note at the top saying the key is allowEnvironmentOverlay from protocol 18 (ADR-0131 C5) and that the old key is a tombstone, plus an Amended-by entry naming ADR-0131; their history lines that describe the field as it was stay as written. A patch changeset for @objectstack/skills carries the published skill line.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CinRQcE6T8SvMbhH8D3NhS
@claude
Merge remote-tracking branch 'origin/main' into claude/issue-22340-s3…
7362ce1 
…-governed-text-rename
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Oct 12, 2026
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 12, 2026
Closed
@objectstack-fleet

objectstack-fleet Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor Author

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 7362ce1211090fe096529128a2d0523a3efca54f
Local-runs: none

Scope: the governed rule-text face — AGENTS.md (rule 7), skills/objectstack-ai/SKILL.md (one published line), docs/adr/0005-metadata-customization-overlay.md and docs/adr/0010-metadata-protection-model.md (a header amendment note each); plus the @objectstack/skills changeset. Inputs: card #22340 (body; the ruling 6073921182; the S2 landing note 6119966926; triage's routing 6121122315; the claim 6121201470; the dev's report 6121766828), PR #23011 (body, the 5-file list, the net diff against main), the check-runs on this head. Read 2026-10-12T09:49Z.

① Derived judgments

  • AGENTS.md rule 7, two lines → two lines: 「Environment-overlay opt-in lives only in allowEnvironmentOverlay on DEFAULT_METADATA_TYPE_REGISTRY — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5.」 RIGHT: the normative line names the key S2 landed (metadata-plugin.zod.ts carries allowEnvironmentOverlay; the old key is a tombstone), no issue number in the operative text, 1109/1116 lines unchanged, region-disjoint from skills(ci): two-speed CI — fast set on PR and merge-queue runs, full battery hourly on main and before a release, main-red stops the lane, four required contexts plus the guard, timing gates report-only, test budgets not deletions #22998's claimed paragraphs.
  • skills/objectstack-ai/SKILL.md:347: allowOrgOverride:false → allowEnvironmentOverlay:false, in place; the value, allowRuntimeCreate:false and the ADR-0063 §2 citation unchanged; tokens 5540 → 5541 under the 6806 ceiling; no number in the line (the id-lint widening to skills/**, PR tooling(pm): check-skill-id-lint scans the published skills/ catalog too #23002, is satisfied in advance). RIGHT: a published skill now teaches the spelling the runtime accepts.
  • ADR-0005 and ADR-0010: one blockquote note each at the top, in ADR-0005's own 「v5.0 update」 voice, naming the protocol-18 spelling, anchoring the declaration site (metadata-plugin.zod.ts#allowEnvironmentOverlay, resolved by check-adr-symbol-anchors), and an Amended by entry naming ADR-0131 C5 / D6 (ADR-0010's header block gains the line). The 12 + 9 history lines naming the old key are untouched. RIGHT: triage's shape (6121122315), decisions not rewritten.
  • No accept set and no public surface changes: S2 carried the widening under its own PASS (6118257575); Clause-②: no is correct here.

② Semver level

skills/objectstack-ai/SKILL.md ships in @objectstack/skills (the fixed group, pre mode next), so the '@objectstack/skills': patch changeset is owed and correct; its body carries the Clause-②: no line as three changesets already on main do. No other package ships these paths. RIGHT.

③ Boundary flags

  • open_questions: none. Premise correction accepted: ADR-0005 has 12 matching history lines, not the 13 the retriage listed.
  • NOT MEASURED, declared to CI: check:dual-build-cjs-loads and check:lean-entry-closure (repo-wide build prerequisites; the diff changes no file any package build reads). 51 of 53 derived families green locally, --ran reconciled.
  • Acceptance notes carried (carrier named or none): scripts/adr-anchors/packages__spec__src__kernel__metadata-plugin.zod.ts.json cites ADR-0005 lines 53–64 for the whitelist table, which the two-line note shifts to 55–66 — no gate reads that range; rides the next PR that edits that file. ADR-0063 line 135 still spells the old key as history — the class triage left as written.
  • Check-runs on this head at review time: 19 success / 3 skipped / 8 in progress, 0 failed; check-governed-merges --pr 23011: Tier H, 22 changed lines.

Implemented-by: claude/issue-22340-s3-governed-text-rename
Reviewed-by: session_01CinRQcE6T8SvMbhH8D3NhS

VERDICT: PASS

Generated by Claude Code

@objectstack-fleet objectstack-fleet Bot added the needs-user-decision Blocked on a maintainer decision — do not dispatch; decision cards only, never on a PR label Oct 12, 2026
@objectstack-fleet

objectstack-fleet Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor Author

维护者速读(终稿)· PR #23011 · #22340(S3)

席位 1(session_01CinRQcE6T8SvMbhH8D3NhS,huangyiirene)对照自己读的 diff(5 文件 +18/−4,四个受管文件 + 一条 changeset)校正 dev 草稿后定稿 · 2026-10-12T09:51Z。

改了什么:把「某类元数据能否被环境覆盖」这个按类型的开关,在四份给 AI 和人读的治理文本里改成代码里现在的名字 allowEnvironmentOverlay(旧名 allowOrgOverride):AGENTS.md 第 7 条规则(原地改,行数不变)、对外发布的 objectstack-ai 技能里的一行,ADR-0005 与 ADR-0010 各在顶部加一段「协议 18 起改名」的说明(照 ADR-0005 自己的「v5.0 update」样式)并登记被 ADR-0131 修订;两份 ADR 正文里描述当年字段的历史叙述原样保留。附一条 @objectstack/skills 的 patch changeset(那一行随技能包发布)。

为什么改:改名本身(S2,PR #22874)已合入——代码、类型和 /meta/types 只认新名,旧名在解析时被拒并提示改名;但 AGENTS.md 和发布的技能还在教旧名,AI 照文档写出的键会被运行时拒收。你 2026-10-09 的裁决(Q1 A · Q2 A,「同意」)定了改名方向;分诊今早把这半边路由到本车道并定了「ADR 只加注不改写」的形状。

风险与代价(含回滚):零运行时风险,只改文字;代价是 @objectstack/skills 下个版本多一条 patch 条目。回滚 = revert 本 PR。本地 53 项门禁 51 绿、2 项需整仓构建留给 CI;CI 在本 head 复核时 19 绿 / 3 跳过 / 8 在跑、0 红。

席位意见:ACCEPT。契约复核(达档、在席)PASS 已贴本 PR。卡不随本 PR 关闭:剩下 cloud 仓两个测试辅助文件里的旧字段名,要能触达 cloud 的席位来做,本 PR 合入后席位把卡退回队列并交分诊改路由。

你要做的:确认两点——① 新名 allowEnvironmentOverlay 与 S2 一致;② ADR 顶部加注的写法可接受——然后给一个 APPROVED review。落地由席位走队列;若 harness 像对 PR #22997 那样以「自我修改」拒绝席位(AGENTS.md 也是 agent 指令面),则请你亲手入队,席位会在卡上说明。

Generated by Claude Code

This was referenced Oct 12, 2026
Open
Open
@os-zhuang
os-zhuang marked this pull request as ready for review October 12, 2026 11:07
@os-zhuang
os-zhuang added this pull request to the merge queue Oct 12, 2026
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 12, 2026
Closed
@objectstack-fleet objectstack-fleet Bot removed the needs-user-decision Blocked on a maintainer decision — do not dispatch; decision cards only, never on a PR label Oct 12, 2026
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 12, 2026
Open
Merged via the queue into main with commit e4a770d Oct 12, 2026
41 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-22340-s3-governed-text-rename branch October 12, 2026 11:32
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 12, 2026
Merged
@github-actions github-actions Bot mentioned this pull request Oct 12, 2026
Closed
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 12, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@os-zhuang os-zhuang os-zhuang approved these changes
@hotlong hotlong Awaiting requested review from hotlong hotlong is a code owner

Assignees

@huangyiirene huangyiirene

Labels

documentation Improvements or additions to documentation size/s tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@os-zhuang @huangyiirene @claude